<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>cpp_bin_float</title>
<link rel="stylesheet" href="../../multiprecision.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
<link rel="up" href="../ref.html" title="Reference">
<link rel="prev" href="mpfr_ref.html" title="mpfr_float_backend">
<link rel="next" href="cpp_dec_ref.html" title="cpp_dec_float">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="mpfr_ref.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp_dec_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_multiprecision.ref.cpp_bin_float_ref"></a><a class="link" href="cpp_bin_float_ref.html" title="cpp_bin_float">cpp_bin_float</a>
</h3></div></div></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">multiprecision</span><span class="special">{</span>

<span class="keyword">enum</span> <span class="identifier">digit_base_type</span>
<span class="special">{</span>
   <span class="identifier">digit_base_2</span> <span class="special">=</span> <span class="number">2</span><span class="special">,</span>
   <span class="identifier">digit_base_10</span> <span class="special">=</span> <span class="number">10</span>
<span class="special">};</span>

<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">unsigned</span> <span class="identifier">Digits</span><span class="special">,</span> <span class="identifier">digit_base_type</span> <span class="identifier">base</span> <span class="special">=</span> <span class="identifier">digit_base_10</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span> <span class="special">=</span> <span class="keyword">void</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Exponent</span> <span class="special">=</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">ExponentMin</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">ExponentMax</span> <span class="special">=</span> <span class="number">0</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">cpp_bin_float</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">50</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">cpp_bin_float_50</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">100</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">cpp_bin_float_100</span><span class="special">;</span>

<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">24</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">126</span><span class="special">,</span> <span class="number">127</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>         <span class="identifier">cpp_bin_float_single</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">53</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">1022</span><span class="special">,</span> <span class="number">1023</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>       <span class="identifier">cpp_bin_float_double</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">64</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">16382</span><span class="special">,</span> <span class="number">16383</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>     <span class="identifier">cpp_bin_float_double_extended</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">113</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int16_t</span><span class="special">,</span> <span class="special">-</span><span class="number">16382</span><span class="special">,</span> <span class="number">16383</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>    <span class="identifier">cpp_bin_float_quad</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">number</span><span class="special">&lt;</span><span class="identifier">backends</span><span class="special">::</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="number">237</span><span class="special">,</span> <span class="identifier">backends</span><span class="special">::</span><span class="identifier">digit_base_2</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">int32_t</span><span class="special">,</span> <span class="special">-</span><span class="number">262142</span><span class="special">,</span> <span class="number">262143</span><span class="special">&gt;,</span> <span class="identifier">et_off</span><span class="special">&gt;</span>  <span class="identifier">cpp_bin_float_oct</span><span class="special">;</span>

<span class="special">}}</span> <span class="comment">// namespaces</span>
</pre>
<p>
        Class template <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
        fulfils all of the requirements for a <a class="link" href="backendconc.html" title="Backend Requirements">Backend</a>
        type. Its members and non-member functions are deliberately not documented:
        these are considered implementation details that are subject to change.
      </p>
<p>
        The class takes six template parameters:
      </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Digits</span></dt>
<dd><p>
              The number of digits precision the type should support. This is normally
              expressed as base-10 digits, but that can be changed via the second
              template parameter.
            </p></dd>
<dt><span class="term">base</span></dt>
<dd><p>
              An enumerated value (either <code class="computeroutput"><span class="identifier">digit_base_10</span></code>
              or <code class="computeroutput"><span class="identifier">digit_base_2</span></code>) that
              indicates whether <code class="computeroutput"><span class="identifier">Digits</span></code>
              is base-10 or base-2
            </p></dd>
<dt><span class="term">Allocator</span></dt>
<dd><p>
              The allocator used: defaults to type <code class="computeroutput"><span class="keyword">void</span></code>,
              meaning all storage is within the class, and no dynamic allocation
              is performed, but can be set to a standard library allocator if dynamic
              allocation makes more sense.
            </p></dd>
<dt><span class="term">Exponent</span></dt>
<dd><p>
              A signed integer type to use as the type of the exponent - defaults
              to <code class="computeroutput"><span class="keyword">int</span></code>.
            </p></dd>
<dt><span class="term">ExponentMin</span></dt>
<dd><p>
              The smallest (most negative) permitted exponent, defaults to zero,
              meaning "define as small as possible given the limitations of
              the type and our internal requirements".
            </p></dd>
<dt><span class="term">ExponentMax</span></dt>
<dd><p>
              The largest (most positive) permitted exponent, defaults to zero, meaning
              "define as large as possible given the limitations of the type
              and our internal requirements".
            </p></dd>
</dl>
</div>
<p>
        The type of <code class="computeroutput"><span class="identifier">number_category</span><span class="special">&lt;</span><span class="identifier">cpp_bin_float</span><span class="special">&lt;</span><span class="identifier">Args</span><span class="special">...&gt;</span> <span class="special">&gt;::</span><span class="identifier">type</span></code> is <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">integral_constant</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span>
        <span class="identifier">number_kind_floating_point</span><span class="special">&gt;</span></code>.
      </p>
<p>
        More information on this type can be found in the <a class="link" href="../tut/floats/cpp_bin_float.html" title="cpp_bin_float">tutorial</a>.
      </p>
<h5>
<a name="boost_multiprecision.ref.cpp_bin_float_ref.h0"></a>
        <span class="phrase"><a name="boost_multiprecision.ref.cpp_bin_float_ref.implementation_notes"></a></span><a class="link" href="cpp_bin_float_ref.html#boost_multiprecision.ref.cpp_bin_float_ref.implementation_notes">Implementation
        Notes</a>
      </h5>
<p>
        Internally, an N-bit <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code>
        is represented as an N-bit unsigned integer along with an exponent and a
        sign. The integer part is normalized so that its most significant bit is
        always 1. The decimal point is assumed to be directly after the most significant
        bit of the integer part. The special values zero, infinity and NaN all have
        the integer part set to zero, and the exponent to one of 3 special values
        above the maximum permitted exponent.
      </p>
<p>
        Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain
        a 2N-bit number, then round and adjust the sign and exponent.
      </p>
<p>
        Addition and subtraction proceed similarly - if the exponents are such that
        there is overlap between the two values, then left shift the larger value
        to produce a number with between N and 2N bits, then perform integer addition
        or subtraction, round, and adjust the exponent.
      </p>
<p>
        Division proceeds as follows: first scale the numerator by some power of
        2 so that integer division will produce either an N-bit or N+1 bit result
        plus a remainder. If we get an N bit result then the size of twice the remainder
        compared to the denominator gives us the rounding direction. Otherwise we
        have one extra bit in the result which we can use to determine rounding (in
        this case ties occur only if the remainder is zero and the extra bit is a
        1).
      </p>
<p>
        Square root uses integer square root in a manner analogous to division.
      </p>
<p>
        Decimal string to binary conversion proceeds as follows: first parse the
        digits to produce an integer multiplied by a decimal exponent. Note that
        we stop parsing digits once we have parsed as many as can possibly effect
        the result - this stops the integer part growing too large when there are
        a very large number of input digits provided. At this stage if the decimal
        exponent is positive then the result is an integer and we can in principle
        simply multiply by 10^N to get an exact integer result. In practice however,
        that could produce some very large integers. We also need to be able to divide
        by 10^N in the event that the exponent is negative. Therefore calculation
        of the 10^N values plus the multiplication or division are performed using
        limited precision integer arithmetic, plus an exponent, and a track of the
        accumulated error. At the end of the calculation we will either be able to
        round unambiguously, or the error will be such that we can't tell which way
        to round. In the latter case we simply up the precision and try again until
        we have an unambiguously rounded result.
      </p>
<p>
        Binary to decimal conversion proceeds very similarly to the above, our aim
        is to calculate <code class="computeroutput"><span class="identifier">mantissa</span> <span class="special">*</span> <span class="number">2</span><span class="special">^</span><span class="identifier">shift</span> <span class="special">*</span> <span class="number">10</span><span class="special">^</span><span class="identifier">E</span></code>
        where <code class="computeroutput"><span class="identifier">E</span></code> is the decimal exponent
        and <code class="computeroutput"><span class="identifier">shift</span></code> is calculated so
        that the result is an N bit integer assuming we want N digits printed in
        the result. As before we use limited precision arithmetic to calculate the
        result and up the precision as necessary until the result is unambiguously
        correctly rounded. In addition our initial calculation of the decimal exponent
        may be out by 1, so we have to correct that and loop as well in the that
        case.
      </p>
</div>
<div class="copyright-footer">Copyright © 2002-2020 John
      Maddock and Christopher Kormanyos<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="mpfr_ref.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="cpp_dec_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
